Inside Macintosh: QuickTime /

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Functions for Getting and Playing Movies / Movie Functions

NewMovieFromHandle

The NewMovieFromHandle function creates a movie in memory from a movie resource or a handle you obtained from the PutMovieIntoHandle function.

pascal OSErr NewMovieFromHandle (Movie *theMovie, Handle h, 
                                 short newMovieFlags, 
                                 Boolean *dataRefWasChanged);

theMovie

Contains a pointer to a field that is to receive the new movie's identifier. If the function cannot load the movie, the returned identifier is set to nil.

h

Contains a handle to the movie resource from which the movie is to be loaded.

newMovieFlags

Controls the operation of the NewMovieFromHandle function. The following flags are available (be sure to set unused flags to 0):

newMovieActive

Controls whether the new movie is active. Set this flag to 1 to make the new movie active. You can make a movie active or inactive by calling the SetMovieActive function, which is described on page 2-131.

newMovieDontResolveDataRefs

Controls how completely the Movie Toolbox resolves data references in the movie resource. If you set this flag to 0, the toolbox tries to completely resolve all data references in the resource. This may involve searching for files on remote volumes. If you set this flag to 1, the Movie Toolbox only looks in the specified file.

If the Movie Toolbox cannot completely resolve all the data references, it still returns a valid movie identifier. In this case, the Movie Toolbox also sets the current error value to couldNotResolveDataRef.

newMovieDontAskUnresolvedDataRefs

Controls whether the Movie Toolbox asks the user to locate files. If you set this flag to 0, the Movie Toolbox asks the user to locate files that it cannot find on available volumes. If the Movie Toolbox cannot locate a file even with the user's help, the function returns a valid movie identifier and sets the current error value to couldNotResolveDataRef.

newMovieDontAutoAlternate

Controls whether the Movie Toolbox automatically selects enabled tracks from alternate track groups. If you set this flag to 1, the Movie Toolbox does not automatically select tracks for the movie--you must enable tracks yourself.

dataRefWasChanged

Contains a pointer to a Boolean value. The Movie Toolbox sets the Boolean value to indicate whether it had to change any data references in order to resolve them. The toolbox sets the Boolean value to true if any references were changed. Set the dataRefWasChanged parameter to nil if you do not want to receive this information.

DESCRIPTION

The NewMovieFromHandle function returns the new movie's identifier. If the function cannot create the movie, the function sets the returned identifier to nil.

Your application can use the NewMovieFromFile function, described in the previous section, to load a movie from a movie file that was opened with the OpenMovieFile function. If you are loading a movie from a resource, use the NewMovieFromFile function instead. The Movie Toolbox uses information about the resource file when it resolves data references in the movie.

The Movie Toolbox sets many movie characteristics to default values. If you want to change these defaults, your application must call other Movie Toolbox functions. For example, the Movie Toolbox sets the movie's graphics world to the one that is active when you call NewMovieFromHandle. To change the graphics world for the new movie, your application should use the SetMovieGWorld function, which is described on page 2-145.

SPECIAL CONSIDERATIONS

The Movie Toolbox automatically sets the movie's graphics world based upon the current graphics port. Be sure that your application's graphics world is valid before you call this function.

ERROR CODES

badImageDescription	-2001	Problem with an image description
badPublicMovieAtom	-2002	Movie file corrupted
cantFindHandler	-2003	Cannot locate a handler
cantOpenHandler	-2004	Cannot open a handler

File Manager errors
Memory Manager errors
Resource Manager errors